Skip to content

CodeClone 2.1.0a1 — Structural Change Controller, Engineering Memory, and native agent integrations#37

Merged
orenlab merged 319 commits into
mainfrom
feat/2.1-alpha
Jun 17, 2026
Merged

CodeClone 2.1.0a1 — Structural Change Controller, Engineering Memory, and native agent integrations#37
orenlab merged 319 commits into
mainfrom
feat/2.1-alpha

Conversation

@orenlab

@orenlab orenlab commented Jun 17, 2026

Copy link
Copy Markdown
Owner

Summary

Opens the CodeClone 2.1 alpha line. Moves CodeClone from a read-only
structural analyzer to an intent-first structural change controller for
AI-assisted Python development, and adds Engineering Memory, trajectory and
experience layers, semantic retrieval, opt-in Platform Observability, native
agent integrations, offline Corpus Analytics, and a reorganized docs site.

Highlights

  • Structural Change Controllerstart_controlled_change /
    finish_controlled_change cut the governed agent edit cycle from 7–11 MCP
    calls to 3–4 (workspace check → intent → blast radius → bounded scope → patch
    verify → claim validation → deterministic receipt). 33 agent-visible MCP tools.
  • Live Implementation Contextget_implementation_context projects
    bounded structural / call-graph / contract evidence from one stored run;
    per-function relationship facts off the canonical report (cache schema 2.9 → 2.10),
    with separate context-artifact and projection digests. Evidence never authorizes
    edits; edit_allowed stays authoritative.
  • Change-intent lifecycle & multi-agent coordinationmanage_change_intent
    (declare / check / clear / queue / promote / recover), renewable leases,
    optional SQLite coordination, workspace hygiene, recoverable-intent handling.
  • Engineering Memory — local SQLite knowledge graph of typed, evidence-linked
    facts; get_relevant_memory / query_engineering_memory; drafts stay
    human-governed (CLI / VS Code Memory view). Never authorizes edits or overrides
    the report, gates, or Patch Trail.
  • Trajectory Memory + Patch Trail + Experience Layer — audit-derived workflows
    with quality passports, complexity scoring, anomaly detection; advisory
    experience patterns (Engineering Memory schema 1.7).
  • Semantic retrieval — optional LanceDB hybrid FTS5/BM25 + vector via
    deterministic Reciprocal Rank Fusion; local embeddings via
    codeclone[semantic-local]; lazy, failure-tolerant, eventually consistent.
  • Platform Observability — opt-in, development-only telemetry of CodeClone's
    own runtime (timings, RSS/CPU, MCP payload/token pressure, DB query shapes,
    causal worker chains, costly no-ops); JSON/HTML cockpit + bounded
    query_platform_observability. Never affects reports, gates, memory, or auth.
  • Native agent integrations — VS Code (memory governance, trajectory
    dashboards, controller audit, session stats), Claude Desktop .mcpb, a
    dedicated Claude Code marketplace plugin, Codex, and Cursor (skills, rules,
    fail-closed preToolUse enforcement, structural-review agent).
  • Corpus Analytics — optional offline clustering of historical change-control
    intents (codeclone[analytics]) with interpretability, versioned profiles, and
    maintainer selection control; artifacts under .codeclone/analytics/.
  • Docs — reorganized thematic contract book + unified integration guides;
    Zensical strict/clean builds.

Changed / migration

  • Default workspace moved .cache/codeclone/.codeclone/ (legacy paths emit a migration warning).
  • pydantic is now a base dependency.
  • LCOM4 excludes Protocol methods and Pydantic validation/serialization hooks (computed_field still counts).
  • Repository test coverage enforced at ≥99%.

Fixed (notable)

  • Durable memory writes (synchronous=FULL) survive unclean MCP exits; atomic memory ingestion (deferred batch commit).
  • Semantic retrieval preserves lexical + vector relevance through RRF; per-source vector budgets; coalesced/deferred projection jobs.
  • Workspace hygiene/intent attribution: finish blocks only on missing evidence or foreign dirty overlap; continue_own_wip resumes owned work.
  • Patch verification rejects identical before/after runs for structural/governance profiles; negative health deltas surface a regression advisory.
  • Architecture: blast-radius graph moved to codeclone/analysis/blast_radius.py, removing the CLI→MCP dependency violation.

Compatibility

  • Cache schema → 2.9 / 2.10 (additive relationship-fact projection; canonical report identity unchanged).
  • Engineering Memory schema 1.7. Read-only MCP semantics and fingerprint contract unchanged.

Release plan

Merge feat/2.1-alphamain now to cut the release. Remaining bugs land on a
follow-up fix/* branch off main. Target: release Monday.

Pre-merge checklist

  • uv run pre-commit run --all-files
  • uv run pytest -q (coverage ≥99%)
  • Docs strict build (zensical build --clean --strict)
  • MCP tool visibility / schema tests (tests/test_mcp_service.py, tests/test_mcp_server.py)

orenlab added 30 commits May 30, 2026 00:23
Add concise tool param descriptions via pydantic Field annotations, reject
cache_policy=refresh at the MCP boundary, and refresh the tool schema
snapshot. Compact agent payloads with next_tool hints, help anti_patterns
in compact mode, trust_boundaries topic, and shorter workflow messages.

Load golden_fixture_paths from pyproject even when respect_pyproject=false
so fixture clones stay suppressed without lowering analysis thresholds.
Refactor duplicated_branches hotspots in workspace intents, session intent
helpers, and Cursor hooks. Update tests, MCP docs, and changelog.
Centralize MCP tool descriptions, help topics, and workflow strings under
codeclone/surfaces/mcp/messages/; update CHANGELOG, AGENTS.md, and docs paths.
Optional sqlite backend keeps closed intents with status transitions
and retention purge (7d default, 14d OSS max), pydantic wire validation,
schema v2, shared sqlite helpers, and plans/retention docs.
Exclude Protocol stub methods and Pydantic validation/serialization hooks
from the LCOM4 graph while keeping computed_field in the graph. Add a one-time
CLI note for trusted 2.0.2 baselines and document applicability in metrics docs.
…ators

Refactor Pydantic contract guards and gc/schema control flow without changing
validation semantics or wire payloads.
Codex plugin instructions and bundled skills now mandate start/finish before
edits and require surfacing structural_delta and receipt advisories even when
finish is accepted. Align CLAUDE.md and Cursor workflow rule with the pipeline.
Cover scope/integrity validators, SQLite store edge paths, and schema migration
branches that were previously untested.
Raise line coverage toward the 99% gate with branch tests for session stats,
patch verify, HTML helpers, extractor edges, and pipeline metrics.
Cover scope/integrity validators, SQLite store edge paths, and schema migration branches that were previously untested.
Raise line coverage toward the 99% gate with branch tests for session stats,
patch verify, HTML helpers, extractor edges, and pipeline metrics.
Advise adding `.cache/codeclone/` when the repository root `.gitignore` does
not cover CodeClone ephemeral state. Surfaces: MCP tips[] on analyze, summary,
triage, and start; CLI tip after interactive runs. Shared check lives in
codeclone/paths/gitignore.py; neither surface edits `.gitignore` automatically
Split PID, staleness, registry lock, and git-scoped hygiene into leaf
modules; dedupe lifecycle predicates and route store GC through staleness.
Add continue_own_wip start policy, after_run_not_new verify guard, health regression advisory, recovery hints, queued-foreign finish hygiene, and patch_health_delta on validate_review_claims.
Document dirty_scope_policy, verify advisories, recovery hints, lazy-close
semantics, and patch_health_delta claim-guard wiring across MCP docs and skills.
Use list_workspace_intent_records_for_recovery so expired_count includes
TTL-expired recoverable intents instead of filtering them out at list time.
Compose MCP session mixins in session.py instead of serial cross-file
inheritance so module import depth drops without changing runtime MRO. Add mypy overrides for composed mixin modules.
Add workspace hygiene and sqlite store lifecycle tests, shared runpy guard helper, global intent-store cache autouse, and coverage for session stats, workflow finish paths, and claim guard behavior.
Fix three documentation-vs-code divergences found during audit:
- add changed_paths/git_diff_ref to analyze_repository param table
- add missing strictness param to finish_controlled_change table
- document all three supported suppression rule IDs

Condense the 2.1.0a1 changelog by merging related items and collapsing
Add coerce_repo_path_tuple and coerce_object_dict helpers for cross-mixin
calls after session flattening; drop no-any-return mypy override and keep
99% coverage without dead internal guard branches.
Consolidate duplicated continue branches in workspace hygiene into _skip_foreign_dirty_record without changing overlap semantics.
# Conflicts:
#	tests/test_workspace_intent_sqlite_store.py
Fix schema versions, source_kind filters, workflow tool guidance, and
read-only semantics across book chapters, extension READMEs, and plugin manifests after the full documentation audit.
Filter Poetry launcher probe subprocess env like exec path. Open Production
Triage fetches get_production_triage with a 5s cooldown and in-flight dedup.
…finish

finish_controlled_change validates claims via claims_text while review_text
stays a human note; finish responses add summary and workspace hygiene.
Workspace intent I/O is thread-safe with correct sqlite closed_at reactivation, shutdown closes audit writers, and worker caches process_file signature lookup.
…s core

Move blast-radius graph traversal to codeclone/analysis/blast_radius.py so
CLI and MCP share neutral logic without surface-layer import violations.
finish_hygiene_check cross-checks the full git tree against finish evidence, blocking under-reported in-scope dirty paths and own unscoped edits while ignoring foreign active/stale intent paths outside declared scope. Sync docs, skills, and CHANGELOG with payload semantics and recoverable nuance.
SQLite store, init ingestion, scoped retrieval, staleness/vacuum,
governance CLI, coverage metrics, MCP tools (get_relevant_memory,
query_engineering_memory, manage_engineering_memory), finish
propose_memory hook, shared file_lock, and baseline refresh for CI.
@orenlab orenlab self-assigned this Jun 17, 2026
@orenlab orenlab added bug Something isn't working documentation Improvements or additions to documentation enhancement New feature or request dependencies Pull requests that update a dependency file python:uv Pull requests that update python:uv code javascript Pull requests that update javascript code labels Jun 17, 2026
Comment thread codeclone/analytics/clustering/canonicalize.py
Comment thread codeclone/analytics/corpus/adapters/intent_historical.py
Comment thread codeclone/analytics/corpus/representations/intent.py
Comment thread codeclone/memory/ingest/extractors.py
Comment thread codeclone/surfaces/cli/memory.py
Comment thread codeclone/surfaces/cli/memory.py
Comment thread codeclone/surfaces/cli/memory.py
Comment thread codeclone/surfaces/cli/workflow.py
@github-actions

Copy link
Copy Markdown

CodeClone Review

✅ Passed · Health 91/100 (A) · Baseline ok · Cache miss · CodeClone 2.1.0a1

Review snapshot

Area Signal Review note
Clones 0 total, 0 new, 0 known no new clone debt reported
Quality CC max 20, CBO max 9, LCOM4 max 3, overloaded 41 structural metric snapshot
Dependencies avg 6.8, p95 21, max 23, cycles 0 acyclic
Coverage Join not joined no coverage.xml facts in this report
Security Surfaces 239 surfaces, 6 categories, 124 production report-only boundary inventory
API Surface 6722 symbols, 611 modules 0 breaking, 0 added
Dead code 0 high-confidence, 2 suppressed clean

Review focus

  • Treat 124 production security surface(s) as review-first boundary code when touched.
  • Review 41 overloaded module candidate(s) when they intersect this PR.

Security Surfaces are report-only capability inventory, not vulnerability claims. Generated by CodeClone

@orenlab orenlab removed the bug Something isn't working label Jun 17, 2026
@orenlab orenlab merged commit 3e3a05a into main Jun 17, 2026
26 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dependencies Pull requests that update a dependency file documentation Improvements or additions to documentation enhancement New feature or request javascript Pull requests that update javascript code python:uv Pull requests that update python:uv code

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants